<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>DonReY Framework :: The Core</title>
<link rel='stylesheet' type='text/css' href='/Documentation/DonReY.css' media='screen' />
</head>
<body>
<a href="/documentation/donrey.html" title="DonReY Framework Documentation">DonReY Framework Documentation</a> &raquo; <a href="/documentation/structure.html" title="Framework structure">Framework structure</a> &raquo; The Core
<hr />
	<h2>DonRey Core &#8211; In the middle of things</h2>

	<p><strong>The DonReY Core</strong> is a static class, which is accessed simply as <strong>core::&#123;method&#125;</strong> or <strong>core::$&#123;member&#125;</strong>. The reason for static class instead of a singleton is that a static can be accessed from anywhere, there is no scope, so no need to pass an object or use &#8230; a static call to access an object. No reason for <em>$this-&gt;</em> inside the core when <em>self::</em> can serve the same purpose. </p>

	<p>The Core is made of these sections:</p>

	<ul>
		<li><a href="#config">Core Configuration repository</a></li>
		<li><a href="#autoload">Core Universal Class Autoloader</a></li>
		<li><a href="core.html#modules">Core Module System</a></li>
		<li><a href="#debug">Core Debugging</a></li>
		<li><a href="core.html#observer">Core Observer Design Pattern</a></li>
		<li><a href="core.html#extra">Extra helper functions</a></li>
	</ul>

	<p>Outside the Core there are a few other objects, in the same file ( core.php ):</p>

	<ul>
		<li><a href="modules.html#baseclass"><span class="caps">DRY</span>_Module_base</a>: Base class for modules</li>
		<li><a href="core.html#template">Mini templating system</a>: Mini-template system, used by Core Debugging, and can be externally used as well.</li>
		<li><a href="core.html#exceptions">Water: the DonReY Internal Exceptions</a>: DonReY&#8217;s internal exceptions system ( used by modules to complain about problems )</li>
		<li><a href="core.html#nonoop">Helpers, non-oop micro-functions</a>: A few functions which are independent of any objects (mostly for development)</li>
	</ul>

	<h3 id="config">Core Configuration repository</h3>

	<p>Inside the bootstrapper, the core is initialized by calling the <strong>&#95;init</strong> method, with the <em>Project-Configuration</em> <span class="caps">XML</span> file as parameter. That method will actually read the <span class="caps">XML</span>, check if it&#8217;s ok, <a href="#debug">crash</a> if not, and place the resulting <a href="http://www.php.net/manual/en/class.simplexmlelement.php">SimpleXMLElement</a> object inside core::$cfg, plus other initializations.</p>

<pre class="php"><span class="sy0"></span>
<span class="co1">// inside the bootstrapper</span>
core<span class="sy0">::</span>_init<span class="br0">&#40;</span>APP_PATH<span class="sy0">.</span> <span class="st_h">'/project-config.xml'</span><span class="br0">&#41;</span><span class="sy0">;</span>
&nbsp;
<span class="co1">// this contains the configuration object</span>
<span class="kw3">var_dump</span><span class="br0">&#40;</span>core<span class="sy0">::</span><span class="re0">$cfg</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="sy0"></span></pre>

	<p>The configuration repository is publicly accesible, and uses references everywhere, so there&#8217;s only one copy of the configuration anywhere in the framework. While no modules modify this object after it&#8217;s been loaded, applications might, however that is not recommended.</p>

	<p>Because it&#8217;s public, it can be used to store application data inside that file which is not of any interest to the core or modules:</p>

<pre class="xml"><span class="sc3"><span class="re1">&lt;?xml</span> <span class="re0">version</span>=<span class="st0">'1.0'</span> <span class="re0">encoding</span>=<span class="st0">&quot;UTF-8&quot;</span> <span class="re2">?&gt;</span></span>
<span class="sc3"><span class="re1">&lt;config<span class="re2">&gt;</span></span></span>
	<span class="sc-1">&lt;!-- debug: disabled / internal / external / all ; outputoncrash: hide / show --&gt;</span>
	<span class="sc3"><span class="re1">&lt;core</span> <span class="re0">debug</span>=<span class="st0">'all'</span> <span class="re0">outputoncrash</span>=<span class="st0">'show'</span><span class="re2">&gt;</span></span>
		<span class="sc-1">&lt;!-- Registers some external libraries locations with the core's autoloader, so they can be included automatically when needed (by some module or user's code) --&gt;</span>	
		<span class="sc3"><span class="re1">&lt;libs<span class="re2">&gt;</span></span></span>
			<span class="sc-1">&lt;!-- name is the library's primary &quot;class&quot;, content is the path ( relative or absolute ) --&gt;</span>
			<span class="sc3"><span class="re1">&lt;FirePHP</span> <span class="re0">rel</span>=<span class="st0">'LIB_PATH'</span><span class="re2">&gt;</span></span>/FirePHP/FirePHP.class.php<span class="sc3"><span class="re1">&lt;/FirePHP<span class="re2">&gt;</span></span></span>
		<span class="sc3"><span class="re1">&lt;/libs<span class="re2">&gt;</span></span></span>
		<span class="sc-1">&lt;!-- Please see Modules documentation page for more info about modules configuration --&gt;</span>
		<span class="sc3"><span class="re1">&lt;modules<span class="re2">&gt;</span></span></span>
		<span class="sc3"><span class="re1">&lt;/modules<span class="re2">&gt;</span></span></span>
	<span class="sc3"><span class="re1">&lt;/core<span class="re2">&gt;</span></span></span>
	<span class="sc-1">&lt;!-- this part is ignored by the core, and any number of elements might exist --&gt;</span>
	<span class="sc3"><span class="re1">&lt;anything<span class="re2">&gt;</span></span></span>
		Hello World, I'm some data needed by the application.
		<span class="sc3"><span class="re1">&lt;element</span> <span class="re0">attribute</span>=<span class="st0">&quot;My Value&quot;</span><span class="re2">&gt;</span></span> content <span class="sc3"><span class="re1">&lt;/element<span class="re2">&gt;</span></span></span>
	<span class="sc3"><span class="re1">&lt;/anything<span class="re2">&gt;</span></span></span>
<span class="sc3"><span class="re1">&lt;/config<span class="re2">&gt;</span></span></span></pre>

	<p>Inside this basic configuration file there you can see the elements:</p>

	<ul>
		<li>config = The root of the Project-Configuration, it can be any name (used <em>config</em> here for clarity)
	<ul>
		<li>libs = Paths for external libraries (See the section <a href="#autoload">Core Universal Class Autoloader</a> for more information)</li>
		<li><ins>modules</ins> = Module specific configuration (See the <a href="modules.html#config">Modules</a> documentation page for more information)</li>
	</ul></li>
		<li><ins>core</ins> = <strong>Required</strong> element, it contains framework specific configuration data</li>
		<li>anything = Something only for the application, ignored by DonReY</li>
	</ul>

	<p>In this example, the attribute in &lt;element&gt; inside &lt;anything&gt; can be accessed from <span class="caps">PHP</span> like this:</p>

<pre class="php"><span class="sy0"></span><span class="kw1">echo</span> core<span class="sy0">::</span><span class="re0">$cfg</span><span class="sy0">-&gt;</span> <span class="me1">anything</span><span class="sy0">-&gt;</span> <span class="me1">element</span><span class="br0">&#91;</span><span class="st_h">'attribute'</span><span class="br0">&#93;</span><span class="sy0">;</span> <span class="co1">// will display &quot;My Value&quot;</span></pre>

	<h3 id="autoload">Core Universal Class Autoloader</h3>

	<p>The Core provides a very useful method of including various <span class="caps">PHP</span> files on the fly, when their class is requested somewhere in the code. Core uses the <span class="caps">PHP</span>&#8217;s __autoload method ( more exactly, the <a href="http://www.php.net/manual/en/function.spl-autoload-register.php">spl_autoload_register</a> method, to redirect any class loading to itself.</p>

	<p>DonReY doesn&#8217;t have a rigid structure for autoloaded classes location, it uses instead <em>path registering</em>:</p>

	<h4>core::register_Autoloader_Path() </h4>

<pre class="php"><span class="kw2">&lt;?php</span>
<span class="re0">$class_prefix</span> <span class="sy0">=</span> <span class="st0">&quot;Some_Class_Prefix_&quot;</span><span class="sy0">;</span>
<span class="re0">$path</span> <span class="sy0">=</span> APP_PATH<span class="sy0">.</span><span class="st0">&quot;/MyClasses/&quot;</span><span class="sy0">;</span>
<span class="re0">$file_suffix</span> <span class="sy0">=</span> <span class="st0">&quot;.php&quot;</span><span class="sy0">;</span>
<span class="re0">$check_function</span> <span class="sy0">=</span> <span class="kw2">function</span><span class="br0">&#40;</span><span class="re0">$class_name_without_prefix</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
	<span class="kw1">return</span> <span class="kw4">true</span><span class="sy0">;</span>
<span class="br0">&#125;</span><span class="sy0">;</span>
<span class="co1">// the path registering method:</span>
core<span class="sy0">::</span><span class="me2">register_Autoloader_Path</span><span class="br0">&#40;</span><span class="re0">$class_prefix</span><span class="sy0">,</span> <span class="re0">$path</span><span class="sy0">,</span> <span class="re0">$file_suffix</span><span class="sy0">,</span> <span class="re0">$check_function</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="sy0"></span></pre>

	<ul>
		<li><strong>$class&#95;prefix</strong> is used to recognise which path to use for a certain class. All classes which start with this prefix will be searched for in the specified $path</li>
		<li><strong>$path</strong> is where the .php files containing classes whose name start with $class&#95;prefix</li>
		<li><strong>$file&#95;suffix</strong> The class name (with prefix substracted) becomes the file name, by adding this suffix (defaults to <strong>.php</strong>)<br />
For example, to instantiate an object of class: <em>Some&#95;Class&#95;Prefix&#95;Hello&#95;World</em>, a file named <em>hello&#95;world.php</em> must exist in /MyClasses</li>
		<li><strong>$check&#95;function</strong> This optional callback is used to check if the class is allowed to be loaded (defaults to null, which means that any class is allowed)</li>
	</ul>

	<p>Any number of directories can be registered, and Core Autoloader will check the proper one. It is possible to register more directories for the same prefix, in which case the loaded file will be the one first found. For example, DonReY Modules themselves can be extended or rewritten by some custom application ! Core attempts to search for modules inside <strong><span class="caps">APP</span>&#95;<span class="caps">PATH</span>.&#8217;/modules/&#8217;</strong>, before checking into <strong><span class="caps">CORE</span>&#95;<span class="caps">PATH</span>.&#8217;/modules/&#8217;</strong>, to permit this kind of extension. The application itself could register other paths for classes that start with <strong>&#8220;Module_&#8221;</strong>, and DonReY will treat those just like any other standard module.</p>

	<p>Default modules use this call extensively to register their own includes (sub-modules, included application files) !</p>

	<h3 id="debug">Core Debugging</h3>

	<p>DonReY has a built-in debugging system, which is both self-contained and extensible through the use of Modules. In this section the self-contained debugging mechanism will be explained, and <a href="modules/debug.html">debugging-related modules</a> will present the extensible version.</p>

	<h4>Configuring debugging system</h4>

	<p><span class="caps">TODO</span>: (<span class="caps">XML</span> core debug config)</p>

	<h4>core::$exc_text</h4>

	<p>This member contains an array of messages for the internal exceptions system. They are stored in an external file (Default: core&amp;#95exceptions&amp;#95english.php), and can be freely modified. Please see this file <a href="http://code.google.com/p/donrey/source/browse/trunk/core_exceptions_english.php">here</a>.</p>

	<h4>core::record_Error()</h4>

	<p>The simplest form of error/problem recording, this method stores a message and associated data in an internal storage, which can be seen in case of a crash or with a debugger module:</p>

<pre class="php"><span class="kw2">&lt;?php</span>
<span class="re0">$type</span> <span class="sy0">=</span> <span class="st0">&quot;INFO&quot;</span><span class="sy0">;</span>  <span class="co1">// can be one of 'EXC', 'WET', 'ERROR', 'WARN', 'INFO' ( Exception, Internal Exception, Error, Warning, Information )</span>
<span class="re0">$message</span> <span class="sy0">=</span> <span class="st0">&quot;This is a debug message&quot;</span><span class="sy0">;</span>
<span class="re0">$error_data</span> <span class="sy0">=</span> <span class="kw3">array</span><span class="br0">&#40;</span><span class="nu0">1</span><span class="sy0">,</span> <span class="nu0">2</span><span class="sy0">,</span> <span class="nu0">3</span><span class="br0">&#41;</span><span class="sy0">;</span> <span class="co1">// data associated with this message</span>
<span class="co1">// the error recording method:</span>
core<span class="sy0">::</span><span class="me2">record_Error</span><span class="br0">&#40;</span><span class="re0">$type</span><span class="sy0">,</span> <span class="re0">$message</span><span class="sy0">,</span> <span class="re0">$error_data</span><span class="br0">&#41;</span><span class="sy0">;</span>
<span class="sy0"></span></pre>

	<p>To display a debug message during the normal execution, a debugger module is required (FirePHP for example), as Core&#8217;s internal methods try to hide problems as much as possible ( until they are really needed to be displayed &#8211; In case of a crash for example ). This is done to prevent leaks to the users in case the application has problems.</p>

	<h4>core::exception_To_Error()</h4>

	<p><span class="caps">TODO</span>.</p>

	<h4>core::_crash()</h4>

	<p>In case the application decides that something has gone terribly wrong ( for example missing some of it&#8217;s data, or inability to connect to a database ), it can force a crash. Calling this method stops all execution and in case debugging is active, display those errors:</p>

<pre class="php"><span class="kw2">&lt;?php</span>
<span class="co1">// sorry, can't take it anymore !</span>
core<span class="sy0">::</span>_crash<span class="br0">&#40;</span><span class="br0">&#41;</span><span class="sy0">;</span>
&nbsp;
<span class="kw1">echo</span> <span class="st0">&quot;This will never get displayed&quot;</span><span class="sy0">;</span>
<span class="sy0"></span></pre>

	<p>In case there&#8217;s a registered debugger module, it will also receive the crash and take action, before the framework is shut down.</p>

	<h4>Catching default <span class="caps">PHP</span> exceptions / errors / warning</h4>

	<p><span class="caps">TODO</span>.</p>
</body>
</html>
<!-- http://www.donrey.net/Documentation - Built with DonReY Framework http://www.donrey.net/ - Powered by PHP, MySQL, JavaScript -->